home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 351-375 / disk_369 / fortune / fortune.doc < prev    next >
Text File  |  1992-05-06  |  8KB  |  189 lines
  1.    Program:  fortune
  2. Programmer:  George Kerber
  3.    Written:  06/16/89          Modified:  04/20/90
  4.    Version:  2.04g
  5.   Compiler:  Lattice 5.05
  6.    Purpose:  Output a "fortune" randomly from a "fortunes" file.
  7.  
  8.  
  9. WORKBENCH USAGE:
  10. ----------------
  11.       Icon:  The fortune program will automatically speak the selected
  12.              fortune if the icon is clicked.
  13.  
  14.  
  15. CLI USAGE:
  16. ----------
  17.     Syntax:  fortune [-l -s -#  [alternate path to the "fortunes" file]]
  18.  
  19.  
  20.              If no alternate path/location is given for the 'fortunes' file,
  21.              first ram:, the the current directory, then the s: directory
  22.              will be searched for the 'fortunes' file.
  23.  
  24.              Users using floppies that execute the fortune program many
  25.              times should copy the fortunes file to ram: for faster
  26.              executions.
  27.  
  28.              If found, fortune will randomly select a fortune and speak (-s)
  29.              it or display it centered on the screen.
  30.  
  31.              -s  speak the fortune instead of screen output,
  32.                     if used, all other options are meaningless.
  33.              -l  the displayed fortune will not have an outline.
  34.              -1  the outline will be white.
  35.              -2  the outline will be black (default).
  36.              -3  the outline will be orange.
  37.          
  38.              If you don't want to store the fortunes file in one of the
  39.              default locations, you can use the command line option to
  40.              specify a different location and/or file name.
  41.  
  42.              Example:
  43.  
  44.              fortune dh0:text/rules  --  will attempt to locate the
  45.                                          "dh0:text/rules" file to select
  46.                                          a fortune from.
  47.  
  48.              fortune ?               --  will display a help screen.
  49.  
  50.              fortune -3              --  will display an orange line before
  51.                                          & after the fortune.
  52.  
  53.              fortune -s              --  the fortune will be spoken using
  54.                                          the speak: device.
  55.  
  56.              The "fortunes" program will attempt to randomly select a 
  57.              "fortune" from the "fortunes" file if it exists.  Or the user
  58.              can enter a fully qualified path/file name as an alternative to
  59.              storing the "fortunes" file in one of the default directories 
  60.  
  61.              (ram: s:)  Included with this program is a "fortunes" file.
  62.  
  63.  
  64. INSTALLATION:
  65. -------------
  66.              Copy the "fortune" file to your "c" directory.
  67.              Copy the "fortunes" file to your "s" directory.
  68.  
  69.              or execute the install script like this:
  70.  
  71.              1> execute fortune.install <enter>
  72.  
  73.              You may want to add "fortune" to your startup sequence.
  74.  
  75.              The 'fortunes' data file can be in the current directory if
  76.              desired, but should really be in the s: directory so it can
  77.              always be found.
  78.  
  79.  
  80. RULES FOR "FORTUNE" FILE CONSTRUCTION
  81. -------------------------------------
  82.  1.  The first line of the file is a comment line & will never be displayed.
  83.  2.  Fortunes can be up to 10 lines in length.
  84.      The first line of each fortune must not have any leading blank spaces.
  85.      Any additional fortunes lines must begin with at least on blank space.
  86.      This is how the program "knows" that there are more lines that need
  87.      to be displayed.
  88.  3.  Fortunes file should be saved as an ASCII file.
  89.      ("ed" or "memacs" is good for this.)
  90.  4.  Each line can be up to 256 characters, but for legibility, they should
  91.      be limited to 74 characters.
  92.  5.  Escape options can be added to the fortunes to display color.
  93.  
  94.      The default escape value is a '*' following standard AmigaDOS format.
  95.      The default value can be changed using the AmigaDOS setenv command.
  96.      Changing the 'escape' character is optional.  
  97.     
  98.      1> setenv ESCAPE=\    ; makes the escape value a backslash
  99.                            ; or whatever you want it to be.
  100.                            ; a backslash is recommended
  101.                            ; You should have this command in your startup
  102.                            ; sequence.
  103.  
  104.      The fortune help screen will always display the current escape value.
  105.  
  106.      These are the valid format characters:
  107.  
  108.      0  Character color will be color 0 (blue)
  109.      1  Character color will be color 1 (white)
  110.      2  Character color will be color 2 (black)
  111.      3  Character color will be color 3 (orange)
  112.      4  All attributes will be reset to preferences
  113.      5  Bold
  114.      6  Underline
  115.      7  Italics
  116.      )  Background color will be color 0   (shift 0)
  117.      !  Background color will be color 1   (shift 1)
  118.      @  Background color will be color 2   (shift 2)
  119.      #  Background color will be color 3   (shift 3)
  120.  
  121.  
  122. EXAMPLES:
  123. ---------
  124. # The first line of the fortunes file is always a "comment" line.
  125. This is line 1 of the fortunes file.
  126. This is *3line*4 2 of the fortunes file.
  127.  This is line 2a of the fortunes file,
  128.  This is line 2b of the *@*3fortunes*4 file,
  129.  This is line 2c of the fortunes file.
  130. This is line 3 of the fortunes file,
  131.  This is the *3*5*6*7second line*4 of line 3.
  132. This is line 4 of the fortunes file.
  133.  
  134.  
  135. Be sure to avoid leaving any blank lines anywhere in the file, including
  136. the last line, the fortune program may randomly select it & display a
  137. blank line.  
  138.  
  139. If an unused option is escaped, fortune will simply ignore it.  For example
  140. if a '*y' is found by the fortune program in the fortunes file, no error
  141. will be displayed, but neither will the '*' or the 'y'.
  142.  
  143.  
  144. SUGGESTIONS:
  145. ------------
  146. Since 'fortune' allows a different text file to be specified on the command
  147. line, you can have different text files for different purposes.  What if
  148. you had a file in your s: directory names 'jokes' which contained jokes
  149. written in the format described above?  And you had a script file called
  150. 'joke' which contained the line below:
  151.  
  152.    fortune s:jokes
  153.  
  154. Then whenever you executed 'joke' you would get a joke from your 'jokes'
  155. file on the screen just like the fortunes file.  Be sure to set the script
  156. bit of the script file for easier executions.  You could have 'joke' and
  157. 'dirty-joke' and 'insult' and 'bible-quote' or whatever you wanted.
  158.  
  159.    fortune -s
  160.  
  161. This will redirect the output of fortune to the speak: device.  You must
  162. have the speak: device already mounted.  All format characters imbedded in
  163. the fortunes data file will be automatically removed.
  164.  
  165.  
  166. STATUS:
  167. -------
  168. Fortune is public domain and can be freely distributed.  Please insure that
  169. I am kept as the author and that all documentation is intact.  If someone
  170. doesn't like one of the fortunes, too bad, the user can delete it.....
  171.  
  172.  
  173.                            George Kerber
  174.                            19756 E. Linvale Drive
  175.                            Aurora, Colorado  80013
  176.                            303-693-2890
  177.  
  178.  
  179. v1.xx  06/29/89:  Initial release.
  180. v2.0   08/03/89:  Rewrote the fortune selection process.  Program now runs
  181.                   from 120 to 290% faster.
  182. v2.03  10/07/89:  Added escape color options for the text file.
  183. v2.04  12/06/89:  Added the speech option.  Recompiled with Lattice 5.04
  184. v2.04c 01/07/90:  Removed all global variables...  PURE?
  185. v2.04f 04/14/90:  Added an icon, and recompiled using a modified version of 
  186.                   the Lattice startup code for a smaller executable.
  187. v2.04g 04/20/90:  Program now seaches the current directory for the
  188.                   'fortunes' file along with ram: and s:
  189.